home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / ref / postquel / retrieve < prev    next >
Encoding:
Text File  |  1992-08-27  |  4.8 KB  |  178 lines
  1. .\" XXX standard disclaimer belongs here....
  2. .\" $Header: /private/postgres/ref/postquel/RCS/retrieve,v 1.10 1992/07/31 17:01:40 mer Exp $
  3. .SP RETRIEVE COMMANDS 6/14/90
  4. .XA 2 Retrieve
  5. .uh NAME
  6. .lp
  7. retrieve \*- retrieve instances from a class
  8. .uh SYNOPSIS
  9. .lp
  10. .(l
  11. \fBretrieve\fR
  12. [ (\fBinto\fR classname [ archive_mode ] | \fBportal\fR portal_name ) | \fBiportal\fR portal_name ]
  13.     [\fBunique\fR]
  14.     \fB(\fR [ attr_name1 \fB=\fR] expression1 {\fB,\fR [attr_name-i \fB=\fR] expression-i} \fB)\fR
  15.     [ \fBfrom\fR from_list ] 
  16.     [ \fBwhere\fR qual ] 
  17.     [ \fBsort\fR \fBby\fR attr_name\-1 [\fBusing\fR operator] { \fB,\fR attr_name-j [\fBusing\fR operator] } ]
  18. .)l
  19. .uh DESCRIPTION
  20. .lp
  21. .b Retrieve 
  22. will get all instances which satisfy the qualification,
  23. .i qual ,
  24. compute the value of each element in the target list,
  25. and either 
  26. return them to an application program through one of two different kinds
  27. of portals
  28. or store them in a new class.
  29. .lp
  30. If
  31. .i classname
  32. is specified, the result of the query will be stored in a new
  33. class with the indicated name.
  34. If an archive specification,
  35. .i archive_mode
  36. of
  37. .b light ,
  38. .b heavy ,
  39. or
  40. .b none
  41. is not specifed, then it
  42. defaults to
  43. .b light
  44. archiving.
  45. (This default may be changed at a site by the
  46. .A DBA .)
  47. The current user will be the owner of the new class.
  48. The class will have attribute names as specified in the 
  49. res_target_list.
  50. A class with this name
  51. owned by the user must not already exist.
  52. The keyword 
  53. .b all
  54. can be used when it is desired to
  55. retrieve all fields of a class.
  56. .lp
  57. If no result
  58. .i classname
  59. is specified, then the result of the query will be
  60. available on the specified portal
  61. and will not be saved.
  62. If no portal name is specified, the blank portal is used by default.
  63. For a portal specified with the 
  64. .b iportal
  65. keyword, retrieve passes data to an application without conversion to
  66. external format.  For a portal specified with the
  67. .b portal
  68. keyword, retrieve passes data to an application after first converting
  69. it to the external representation.
  70. For the blank portal, all data is converted to external format.
  71. Duplicate instances are not removed when the result is
  72. displayed through a portal
  73. unless the optional
  74. .b unique
  75. tag is appended, in which case the instances in the res_target_list
  76. are sorted according to the sort clause and duplicates are
  77. removed before being returned.
  78. .lp
  79. Instances retrieved into a portal may be fetched in subsequent
  80. queries by using the
  81. .b fetch
  82. command.
  83. Since the results of a
  84. .b "retrieve portal"
  85. span queries,
  86. .b "retrieve portal"
  87. may only be executed inside of a
  88. \fBbegin\fP/\fBend\fP
  89. transaction block.
  90. Attempts to use named portals outside of a transaction
  91. block will result in a warning message from the parser,
  92. and the query will be discarded.
  93. .lp
  94. The
  95. .b sort
  96. clause allows a user to specify that he wishes the instances sorted
  97. according to the corresponding operator.
  98. This operator must be a binary one returning a boolean.
  99. Multiple sort fields are allowed and are applied from left to right.
  100. .uh EXAMPLE
  101. .lp
  102. .nf
  103. .ft C
  104. /* Find all employees who make more than their manager */
  105.  
  106. retrieve (e.name)
  107.    from e, m in emp
  108.    where e.mgr = m.name
  109.    and e.sal > m.sal
  110.  
  111. /*
  112.  * Retrieve all fields for those employees who make
  113.  * more than the average salary
  114.  */
  115.  
  116. retrieve into avgsal(ave = float8ave {emp.sal}) \eg
  117.  
  118. retrieve (e.all)
  119.    from e in emp
  120.    where e.sal > avgsal.ave \eg
  121.  
  122. /* retrieve employees's names sorted */
  123.  
  124. retrieve unique (emp.name)
  125.    sort by name using <
  126.  
  127. /* retrieve all employees's names that were valid on 1/7/85 
  128.    in sorted order */
  129.  
  130. retrieve (e.name)
  131.    from e in emp["January 7 1985"]
  132.    sort by name using <
  133.  
  134. /* construct a new class, raise, containing 1.1 */
  135. /* times all employee's salaries                */
  136.  
  137. retrieve into raise (salary = 1.1 * emp.salary)
  138.  
  139. /* do a retrieve into a portal */
  140. begin \eg
  141.    retrieve portal myportal (pg_user.all) \eg
  142.    fetch 2 in myportal \eg
  143.    fetch all in myportal \eg
  144.    close myportal \eg
  145. end \eg
  146. .ft
  147. .uh "SEE ALSO"
  148. .lp
  149. postquel(commands),
  150. fetch(commands),
  151. close(commands),
  152. create(commands).
  153. .uh BUGS
  154. .lp
  155. .q "Retrieve into"
  156. does not delete duplicates in Version \*(PV.
  157. .lp
  158. .q Archive_mode 
  159. is not implemented in Version \*(PV.
  160. .lp
  161. If the backend crashes in the course of executing a 
  162. .q "Retrieve into,"
  163. the class file will remain on disk.  It can be safely removed by the
  164. database DBA, but a subsequent 
  165. .b retrieve
  166. .b into
  167. to the same name will fail with a cryptic error message about "BlockExtend".
  168. A solution to this problem is being investigated and will be released in
  169. later version.
  170. .lp
  171. .q "Retrieve iportal"
  172. returns data in an architecture dependent format, namely that of the
  173. server on which the backend is running.  A standard data format should
  174. be adopted, most likely XDR.  At that point, there will be no need to
  175. distinguish among external and internal data.
  176. .lp
  177. Aggregate functions must appear in the target list.
  178.